<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Send and Receive</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="kvaser.gif"/></td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_user_guide_send_recv.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Send and Receive </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#section_user_guide_send_recv_bus_on_off">Bus On / Bus Off</a></li>
<li class="level1"><a href="#section_user_guide_send_recv_reading">Reading Messages</a></li>
<li class="level1"><a href="#section_user_guide_send_recv_filters">Acceptance Filters</a><ul><li class="level2"><a href="#section_user_guide_misc_code_and_mask">Code and Mask Format</a></li>
</ul>
</li>
<li class="level1"><a href="#section_user_guide_send_recv_sending">Sending Messages</a></li>
<li class="level1"><a href="#section_user_guide_send_recv_obj_buf">Object Buffers</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="section_user_guide_send_recv_bus_on_off"></a>
Bus On / Bus Off</h1>
<p>When the CAN controller is on bus, it is receiving messages and is sending acknowledge bits in response to all correctly received messages. A controller that is off bus is not taking part in the bus communication at all.</p>
<p>Use <a class="el" href="group___c_a_n.html#ga99c7c99cc71580f8099a1407f4f9ea1a">canBusOn()</a> to go on bus and <a class="el" href="group___c_a_n.html#gaf1786cfbfd542b18b9c599d278837bd9">canBusOff()</a> to go off bus.</p>
<p>If you have multiple handles to the same controller, the controller will go off bus when the last of the handles go off bus (i.e. all handles must be off bus for the controller to be off bus). You can use <a class="el" href="group___c_a_n.html#gaca3da209fe673b3838a50a3abe831855">canReadStatus()</a> and watch the flag <a class="el" href="canstat_8h.html#aab3d45d8b4e8bfbba45d585fb6195fbf">canSTAT_BUS_OFF</a> to see if the controller has gone off bus.</p>
<p>If you would like to reset a CAN bus controller by taking the channel off bus and then on bus again, you can use <a class="el" href="group___c_a_n.html#gaecc8b56e75cf68548af53b2d432079af">canResetBus()</a>.</p>
<p>You can set a channel to silent mode by using the <a class="el" href="canlib_8h.html#ab82a818e60cddf4c65c54d42a474a023">canDRIVER_SILENT</a> mode if you want it to be on-bus without interfering with the traffic in any way, see <a class="el" href="page_user_guide_chips_channels.html#section_user_guide_init_driver_modes">CAN Driver Modes</a></p>
<p><b>Example</b>. This example takes an open channel off-bus and then takes it on-bus again, for what purpose it may serve.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"></div><div class="line">.</div><div class="line">.</div><div class="line">.</div><div class="line">stat = <a class="code" href="group___c_a_n.html#gaf1786cfbfd542b18b9c599d278837bd9">canBusOff</a>(hnd);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;canBusOff failed, status=%d\n&quot;</span>, stat);</div><div class="line">    exit(1);</div><div class="line">}</div><div class="line"></div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga99c7c99cc71580f8099a1407f4f9ea1a">canBusOn</a>(hnd);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;canBusOn failed, status=%d\n&quot;</span>, stat);</div><div class="line">    exit(1);</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="section_user_guide_send_recv_reading"></a>
Reading Messages</h1>
<p>Incoming messages are placed in a queue in the driver. In most cases the hardware does message buffering as well. You can read the first message in the queue by calling <a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead()</a>; it will return <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a734089f351bc421c230bf8b6cd9b1e8e">canERR_NOMSG</a> if there was no message available.</p>
<p>The flag parameter of <a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead()</a> contains a combination of the message flags <a class="el" href="canstat_8h.html#canMSG_xxx">canMSG_xxx</a>, including <a class="el" href="canstat_8h.html#canFDMSG_xxx">canFDMSG_xxx</a> if the CAN FD protocol is enabled, and error flags <a class="el" href="canstat_8h.html#canMSGERR_xxx">canMSGERR_xxx</a> which provides you with more information about the message; for example, a frame with a 29-bit identifier will have the <a class="el" href="canstat_8h.html#ade936f23b4b303d64187b4c6589c9c10">canMSG_EXT</a> bit set, and a remote frame will have the <a class="el" href="canstat_8h.html#a687df04559a9995e0bec503655454eb3">canMSG_RTR</a> bit set. Note that the flag argument is a combination of the <a class="el" href="canstat_8h.html#canMSG_xxx">canMSG_xxx</a> flags, so more than one bit might be set.</p>
<p>See <a class="el" href="page_user_guide_can_frame_types_types.html">CAN Frame Types</a> Different for more detailed information.</p>
<p>The size of the queues in the driver and hardware is described in <a class="el" href="page_user_guide_send_recv_mailboxes.html#section_user_guide_send_recv_queue_and_buf_sizes">Message Queue and Buffer Sizes</a>.</p>
<p>Sometimes it is desirable to have a peek into the more remote parts of the queue. Is there, for example, any message waiting that has a certain identifier?</p>
<ul>
<li><a class="el" href="group___c_a_n.html#gafb5e475233ef14ccf9084f610caba560">canReadSpecific()</a> - You can call <a class="el" href="group___c_a_n.html#gafb5e475233ef14ccf9084f610caba560">canReadSpecific()</a> to read that message. Messages not matching the specified identifier will be kept in the queue and will be returned on the next call to <a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead()</a>.</li>
<li><a class="el" href="group___c_a_n.html#ga0eecb6695653d4dc6a4c0bb884a1b261">canReadSpecificSkip()</a> - If you want to read just a message with a specified identifier, and throw all others away, you can call <a class="el" href="group___c_a_n.html#ga0eecb6695653d4dc6a4c0bb884a1b261">canReadSpecificSkip()</a>. This routine will return the first message with the specified identifier, discarding any other message in front of the desired one.</li>
<li><a class="el" href="group___c_a_n.html#gac01f98e282609b5f6aaf2b1eabfb83ec">canReadWait()</a> - If you want to wait until a message arrives (or a timeout occurs) and then read it, call <a class="el" href="group___c_a_n.html#gac01f98e282609b5f6aaf2b1eabfb83ec">canReadWait()</a>.</li>
<li><a class="el" href="group___c_a_n.html#ga16356f4d646240ff2e640773d21f4d76">canReadSync()</a> - If you want just to wait for an arbitrary message to arrive, but you don't want to read the message, call <a class="el" href="group___c_a_n.html#ga16356f4d646240ff2e640773d21f4d76">canReadSync()</a>.</li>
<li><a class="el" href="group___c_a_n.html#ga4b21a0e2547c1435c378d13e6803acef">canReadSyncSpecific()</a> - If you want to wait until there is at least one message in the queue with a certain identifier, but you don't want to read it, call <a class="el" href="group___c_a_n.html#ga4b21a0e2547c1435c378d13e6803acef">canReadSyncSpecific()</a>.</li>
</ul>
<p>You can specify a timeout (in milliseconds) for those routines that wait for messages.</p>
<p><b>Example</b>. Input Queue Handling</p>
<p>As an illustration of the abovementioned routines, consider the case where CAN messages with the following identifiers have arrived to the input queue:</p>
<p>1, 2, 3, 4, 5, 6, 7, 8, 9, 10</p>
<ol type="1">
<li><a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;id, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and id == 1.</li>
<li><a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;id, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and id == 2.</li>
<li><a class="el" href="group___c_a_n.html#gafb5e475233ef14ccf9084f610caba560">canReadSpecific</a>(hnd, 7, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and the message with id 7.</li>
<li><a class="el" href="group___c_a_n.html#gafb5e475233ef14ccf9084f610caba560">canReadSpecific</a>(hnd, 7, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a734089f351bc421c230bf8b6cd9b1e8e">canERR_NOMSG</a>.</li>
<li><a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;id, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and id == 3.</li>
<li><a class="el" href="group___c_a_n.html#ga0eecb6695653d4dc6a4c0bb884a1b261">canReadSpecificSkip</a>(hnd, 5, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and the message with id 5.</li>
<li><a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;id, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and id == 6.</li>
<li><a class="el" href="group___c_a_n.html#ga4b21a0e2547c1435c378d13e6803acef">canReadSyncSpecific</a>(hnd, 7, &hellip;, 500) will wait for the next message with id=7 (or 500 ms have elapsed) and return <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> or <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7acd1c4c3a87dd24f0a43753ee4bfe7993">canERR_TIMEOUT</a>.</li>
<li><a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;id, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and id == 8.</li>
<li><a class="el" href="group___c_a_n.html#gafb5e475233ef14ccf9084f610caba560">canReadSpecific</a>(hnd, 7, &hellip;) returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a> and the message with id = 7, if the previous call to <a class="el" href="group___c_a_n.html#ga4b21a0e2547c1435c378d13e6803acef">canReadSyncSpecific()</a> returned <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a49743d0d438957118b9c6af2e831b209">canOK</a>.</li>
</ol>
<p><b>Example</b>. The following code fragment reads the next available CAN message, if any. </p><div class="fragment"><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"><span class="keywordtype">long</span> id;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> data[8];</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> dlc, flags;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> timestamp;</div><div class="line"></div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;<span class="keywordtype">id</span>, data, &amp;dlc, &amp;flags, &amp;timestamp);</div><div class="line"><span class="keywordflow">if</span> (stat != <a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a734089f351bc421c230bf8b6cd9b1e8e">canERR_NOMSG</a>) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, status == %d\n&quot;</span>, stat);</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="section_user_guide_send_recv_filters"></a>
Acceptance Filters</h1>
<p>You can set filters to reduce the number of received messages. CANlib supports setting of the hardware filters on the CAN interface board. This is done either with the <a class="el" href="group___c_a_n.html#gaa4ffd2fad1932ad5763c2c923a1a12d8">canAccept()</a> function or with the <a class="el" href="group___c_a_n.html#gabe5023aa5de3115de946a6a10232fe84">canSetAcceptanceFilter()</a> function.</p>
<p>Note that both functions distinguish between 11-bit (std) and 29-bit (ext) identifiers since these are handled by two separate filters. Both of these filters default to OFF (mask == 0).</p>
<p>You set an acceptance code and an acceptance mask which together determine which CAN identifiers are accepted or rejected.</p>
<p>If you want to remove a filter, call <a class="el" href="group___c_a_n.html#gaa4ffd2fad1932ad5763c2c923a1a12d8">canAccept()</a> with the mask set to 0.</p>
<p><b>Example</b>. To set the mask to 0xF0 and the code to 0x60: </p><div class="fragment"><div class="line">stat = <a class="code" href="group___c_a_n.html#gaa4ffd2fad1932ad5763c2c923a1a12d8">canAccept</a>(hnd1, 0x0F0L, <a class="code" href="canlib_8h.html#a8665c92e40adccfacc238af38b39f37e">canFILTER_SET_MASK_STD</a>);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) printf(<span class="stringliteral">&quot;canAccept failed, stat = %d\n&quot;</span>, stat);</div><div class="line">stat = <a class="code" href="group___c_a_n.html#gaa4ffd2fad1932ad5763c2c923a1a12d8">canAccept</a>(hnd1, 0x060L, <a class="code" href="canlib_8h.html#a9485f417c3629b9eb72d673b3ff16a5f">canFILTER_SET_CODE_STD</a>);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) printf(<span class="stringliteral">&quot;canAccept failed, stat = %d\n&quot;</span>, stat);</div></div><!-- fragment --><p>or, alternatively,</p>
<div class="fragment"><div class="line">stat = <a class="code" href="group___c_a_n.html#gabe5023aa5de3115de946a6a10232fe84">canSetAcceptanceFilter</a>(hnd1, 0x060, 0x0F0, FALSE);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) printf(<span class="stringliteral">&quot;canSetAcceptanceFilter failed, stat = %d\n&quot;</span>, stat);</div></div><!-- fragment --><p>This code snippet will cause all messages having a standard (11-bit) identifier with bit7-bit4 in the identifier equal to 0110 (binary) will pass through. Other messages with standard identifiers will be rejected.</p>
<p><b>Example</b>. How acceptance filters can be used in a smaller project. </p><div class="fragment"><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"><span class="keywordtype">long</span> id;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> data[8];</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> dlc, flags;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> timestamp;</div><div class="line"></div><div class="line"><span class="comment">// The acceptance filter only have to be called once for each handle.</span></div><div class="line">stat = <a class="code" href="group___c_a_n.html#gabe5023aa5de3115de946a6a10232fe84">canSetAcceptanceFilter</a>(hnd, 0x060, 0x0F0, FALSE);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) printf(<span class="stringliteral">&quot;canSetAcceptanceFilter failed, stat = %d\n&quot;</span>, stat);</div><div class="line"></div><div class="line"><span class="comment">// We can now run the rest of the program and the acceptance filter will reject unwanted CAN messages.</span></div><div class="line"><span class="keywordflow">while</span> (<span class="keyword">true</span>){</div><div class="line">    stat = <a class="code" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead</a>(hnd, &amp;<span class="keywordtype">id</span>, data, &amp;dlc, &amp;flags, &amp;timestamp);</div><div class="line">    <span class="keywordflow">if</span> (stat != <a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a734089f351bc421c230bf8b6cd9b1e8e">canERR_NOMSG</a>) {</div><div class="line">        printf(<span class="stringliteral">&quot;Failed, status == %d\n&quot;</span>, stat);</div><div class="line">    }</div><div class="line">}</div></div><!-- fragment --><h2><a class="anchor" id="section_user_guide_misc_code_and_mask"></a>
Code and Mask Format</h2>
<p>Explanation of the code and mask format used by the <a class="el" href="group___c_a_n.html#gaa4ffd2fad1932ad5763c2c923a1a12d8">canAccept()</a>, and <a class="el" href="group___object_buffers.html#gaccca9d669c981e910c1805614ee40e72">canObjBufSetFilter()</a> functions:</p>
<ul>
<li>A binary 1 in a mask means "the corresponding bit in the code is relevant"</li>
<li>A binary 0 in a mask means "the corresponding bit in the code is not relevant"</li>
<li>A relevant binary 1 in a code means "the corresponding bit in the identifier must be 1"</li>
<li>A relevant binary 0 in a code means "the corresponding bit in the identifier must be 0"</li>
</ul>
<p>In other words, the message is accepted if ((code XOR id) AND mask) == 0.</p>
<dl class="section note"><dt>Note</dt><dd>You can set the extended code and mask only on CAN boards that support extended identifiers.</dd>
<dd>
Not all CAN boards support different masks for standard and extended CAN identifiers.</dd>
<dd>
On some boards the acceptance filtering is done by the CAN hardware; on other boards (typically those with an embedded CPU,) the acceptance filtering is done by software. <a class="el" href="group___c_a_n.html#gaa4ffd2fad1932ad5763c2c923a1a12d8">canAccept()</a> behaves in the same way for all boards, however.</dd></dl>
<h1><a class="anchor" id="section_user_guide_send_recv_sending"></a>
Sending Messages</h1>
<p>You transmit messages by calling <a class="el" href="group___c_a_n.html#ga62c185329d6741c90102511e2f37983e">canWrite()</a>. Outgoing CAN messages are buffered in a transmit queue and sent on a First-In First-Out basis. You can use <a class="el" href="group___c_a_n.html#ga304cb3a7bc2874c1f8ad361a911bcd5f">canWriteSync()</a> to wait until the messages in the queue have been sent.</p>
<p><b>Example</b>. Sending a CAN message.</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span> msg[8];</div><div class="line">...</div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga62c185329d6741c90102511e2f37983e">canWrite</a>(hnd, 234, msg, 8, 0);</div></div><!-- fragment --><p><b>Using Extended CAN (CAN 2.0B)</b></p>
<p>"Standard" CAN has 11-bit identifiers in the range 0 - 2047. "Extended" CAN, also called CAN 2.0B, has 29-bit identifiers. You specify which kind of identifiers you want to use in your call to <a class="el" href="group___c_a_n.html#ga62c185329d6741c90102511e2f37983e">canWrite()</a>: if you set the <a class="el" href="canstat_8h.html#ade936f23b4b303d64187b4c6589c9c10">canMSG_EXT</a> flag in the flag argument, the message will be transmitted with a 29-bit identifier. Conversely, received 29-bit-identifier messages have the <a class="el" href="canstat_8h.html#ade936f23b4b303d64187b4c6589c9c10">canMSG_EXT</a> flag set.</p>
<p><b>Example</b>. The following code fragment sends a CAN message on an already open channel. The CAN message will have identifier 1234 (extended) and DLC = 8. The contents of the data bytes will be whatever the data array happens to contain.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> data[8];</div><div class="line"> :</div><div class="line"> :</div><div class="line"></div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga62c185329d6741c90102511e2f37983e">canWrite</a>(hnd, 1234, data, 8, canMSG_EXT);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Failed, status == %d\n&quot;</span>, stat);</div><div class="line">}</div></div><!-- fragment --><p>There are more (but not all) of the message flags <a class="el" href="canstat_8h.html#canMSG_xxx">canMSG_xxx</a>, including <a class="el" href="canstat_8h.html#canFDMSG_xxx">canFDMSG_xxx</a> if the CAN FD protocol is enabled, that are meaningful to set when sending messages.</p>
<h1><a class="anchor" id="section_user_guide_send_recv_obj_buf"></a>
Object Buffers</h1>
<p>Some of the Kvaser interfaces are equiped with hardware buffers for automatic sending and responding to messages. They can be used when the timing conditions are strict, and might not be possible to fulfill on the application level.</p>
<p>There are two types of buffers, auto response and auto transmit.</p><ul>
<li><b>Auto response</b> sends a defined message immediately upon receiving a message meeting your conditions.</li>
<li><b>Auto transmit</b> sends a message periodically, with higher timing accuracy than can be achieved by an application working through driver and operating system.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>The object buffers are implemented by the firmware and hardware of certain devices, e.g. the Kvaser Leaf Professional. The number of buffers are, depending on the device, typically limited to around 8 buffers.</dd></dl>
<p><b>Using the object buffers</b><br />
 To use the object buffers, start by allocating buffer with a call to <a class="el" href="group___object_buffers.html#gaa189a35c78004d037eed4bd0c2bfa3ee">canObjBufAllocate()</a> and set the content of the buffer with <a class="el" href="group___object_buffers.html#gad72611f11b4947c96c8d0b50f59b2173">canObjBufWrite()</a>.</p>
<p>For auto response you define which messages to respond to by calling <a class="el" href="group___object_buffers.html#gaccca9d669c981e910c1805614ee40e72">canObjBufSetFilter()</a>. The filter uses a code and mask, which means it can be set to respond to a range of CAN ids.</p>
<p>For automatic transmission the delay between each message sent is set by calling <a class="el" href="group___object_buffers.html#gaa23baa37921bf089d9123eb97f32541b">canObjBufSetPeriod()</a>. To limit the number of messages sent by the buffer make a call to <a class="el" href="group___object_buffers.html#ga769ce97c3b7f3a8e246f872d7dbafe54">canObjBufSetMsgCount()</a>.</p>
<p>To enable the buffer make a call to <a class="el" href="group___object_buffers.html#ga1ff3e82f6d0e9795a831e22183c6e7ec">canObjBufEnable()</a>. The buffer can be disabled by <a class="el" href="group___object_buffers.html#gab1238b563ecf4523092ebe561ece87ea">canObjBufDisable()</a>.</p>
<p>You can deallocate a buffer that you don't want to use any longer by a call to <a class="el" href="group___object_buffers.html#ga7353b3671b897e1f33b88f9084857382">canObjBufFree()</a>, or to deallocate all buffers in one call use <a class="el" href="group___object_buffers.html#gab299ecf20aa368b8ee253ba9610dff3b">canObjBufFreeAll()</a>.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group___object_buffers.html#ga9369c2f47886d9f815fe5513d6f5b60b">canObjBufSetFlags()</a></dd></dl>
<p><b>Example Auto Response.</b><br />
 This example responds with "1 2 3 4 5 6" with id "200" when a message with the id "100" is recieved. </p><div class="fragment"><div class="line"><span class="comment">// Allocate buffer for auto response</span></div><div class="line"><span class="keywordtype">int</span> bufIndex = <a class="code" href="group___object_buffers.html#gaa189a35c78004d037eed4bd0c2bfa3ee">canObjBufAllocate</a>(handle, <a class="code" href="canlib_8h.html#ae9a5acc70f888bcee736499be5440e91">canOBJBUF_TYPE_AUTO_RESPONSE</a>);</div><div class="line"></div><div class="line"><span class="comment">// Define message</span></div><div class="line"><span class="keywordtype">char</span> msg[] = { 1,2,3,4,5,6 };</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> status;</div><div class="line"></div><div class="line"><span class="comment">// Write to buffer.</span></div><div class="line">status = <a class="code" href="group___object_buffers.html#gad72611f11b4947c96c8d0b50f59b2173">canObjBufWrite</a>(handle, bufIndex, 200, msg, 0, 0);</div><div class="line"></div><div class="line"><span class="comment">// Only match message with id 100, match all bits.</span></div><div class="line">status = <a class="code" href="group___object_buffers.html#gaccca9d669c981e910c1805614ee40e72">canObjBufSetFilter</a>(handle, bufIndex, 100, 0xFFFF);</div><div class="line"></div><div class="line"><span class="comment">// Activate the buffer</span></div><div class="line">status = <a class="code" href="group___object_buffers.html#ga1ff3e82f6d0e9795a831e22183c6e7ec">canObjBufEnable</a>(handle, bufIndex);</div><div class="line"></div><div class="line"><a class="code" href="group___c_a_n.html#ga99c7c99cc71580f8099a1407f4f9ea1a">canBusOn</a>(handle);</div></div><!-- fragment --><p><b>Example Auto Transmit.</b><br />
 This example transmit "1 2 3 4 5 6" with id "300" every second. </p><div class="fragment"><div class="line"><span class="comment">//Allocate buffer</span></div><div class="line"><span class="keywordtype">int</span> bufIndex = <a class="code" href="group___object_buffers.html#gaa189a35c78004d037eed4bd0c2bfa3ee">canObjBufAllocate</a>(handle, <a class="code" href="canlib_8h.html#aa9f7e8efd410139b455bd2caac937094">canOBJBUF_TYPE_PERIODIC_TX</a>);</div><div class="line"></div><div class="line"><span class="comment">//define message</span></div><div class="line"><span class="keywordtype">char</span> msg[] = { 1, 2, 3, 4, 5, 6 };</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> status;</div><div class="line"></div><div class="line"><span class="comment">//Write to buffer</span></div><div class="line">status = <a class="code" href="group___object_buffers.html#gad72611f11b4947c96c8d0b50f59b2173">canObjBufWrite</a>(handle, bufIndex, 300, msg, 0, 0);</div><div class="line"></div><div class="line"><span class="comment">//Set period to 1 second (1000000 microseconds)</span></div><div class="line">status = <a class="code" href="group___object_buffers.html#gaa23baa37921bf089d9123eb97f32541b">canObjBufSetPeriod</a>(handle, bufIndex, 1000000);</div><div class="line"></div><div class="line"><span class="comment">//Limit the transmition to 5 messages</span></div><div class="line"><a class="code" href="group___object_buffers.html#ga769ce97c3b7f3a8e246f872d7dbafe54">canObjBufSetMsgCount</a>(handle, bufIndex, 5);</div><div class="line"></div><div class="line"><span class="comment">//activate the buffer</span></div><div class="line">status = <a class="code" href="group___object_buffers.html#ga1ff3e82f6d0e9795a831e22183c6e7ec">canObjBufEnable</a>(handle, bufIndex);</div><div class="line"></div><div class="line"><a class="code" href="group___c_a_n.html#ga99c7c99cc71580f8099a1407f4f9ea1a">canBusOn</a>(handle);</div></div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="page_canlib.html">CAN bus API (CANlib)</a></li>
    <li class="footer"> (canlib 5.38) Tue Feb 15 2022</li>
  </ul>
</div>
</body>
</html>
